How to create your own bot
Note: If you need help with this bot then you should contact Kocka. Hey! If you're on this user subpage, it means I or somebody else directed you to it when you asked how to make a chat bot. This page should explain that. Kind of. This documentation might be outdated, so if you're confident in your Ruby knowledge you might as well want to check out the latest commits to see what changed since the last documentation update. Introduction : Read this section. I know reading is boring but if you don't read this part you'll most probably get confused later. Believe me, it's worth it. Chat bot is just like a normal user in chat, except that it takes automatic action under certain circumstances. Some examples of how can it be used are logging chat, automatically detecting chat policy violations (caps, swearing) and taking automated actions to prevent them (warnings, kicks, bans), checking when was a user last time on chat, delivering a message to the user while they are out of chat or even relaying the chat to Discord. But before setting up a chat bot, ask yourself if you really need any of those features, or you wanted to make a chat bot just to look cool. The fact is, a lot of the features chat bots across FANDOM provide are already covered by Discord's functionalities, either its core features or its user-made and user-maintained bots. Unlike the Chat extension on FANDOM, Discord is a whole platform dedicated to chatting (that, despite their branding, is not only "for gamers") and is years ahead of the Chat extension in terms of functionality, API, integration, etc. I'm not going to continue with promotion of Discord in this paragraph as it's largely irrelevant to the article, but at the point of needing a bot for your chat you should probably make the decision whether to remain on FANDOM Chat or use one of the Discord integration scripts and move your chatting community to Discord. chatbot-rb is a chat bot framework built by Kerri Amber. Due to an unfortunate accident, the original chatbot-rb repository has been deleted and I kept the last stable version in my fork of it. Requirements In order to make a chat bot, you need to fulfill these requirements: # Have a permission from administration/community. If you are a regular user on the wiki, and want to set up a chat bot, you need to ask the administration to allow that. If you are already in the local administration of that wiki, it might be a good idea to inform others users of the wiki about the chat bot. # Have a computer you can leave running all the time. A chat bot is a program. If you run that program, the chat bot is in chat. If you don't run it, it isn't in chat. So if you want your chat bot to be in chat all the time, you have to run it all the time, which requires the machine the chat bot is running on to be turned on all the time. # Don't be globally blocked. Easy enough? If you don't fulfill those requirements, there's no need to proceed to the installation section. Installation Now, these are the installation steps for the chat bot. Ruby As chatbot-rb is built on Ruby, it also requires a Ruby interpreter in order to be run. ; Windows : To install Ruby on Windows, download the latest version of Ruby from this page. Complete the installation process properly, and do not forget to check "Add Ruby executables to your PATH". ; Linux : To install Ruby on Linux, install Ruby Version Manager (RVM) as described here. Or just Google it, it shouldn't be too hard. Remember not to use sudo when installing it, though. Or something like that, I forgot as I installed it long ago. ; Mac OS : I dunno, I don't use Mac. Dependencies After installing Ruby, you need to install chatbot-rb dependencies. You can do that by opening your console window (on Windows, click Windows Button + R and in the Run window that appears enter "cmd" and then click the OK button). After the console window is open, enter gem install httparty mediawiki-gateway in it. If installing these fails because an SSL certificate is invalid, please update your RubyGems. Account While you're waiting for Ruby and dependencies to get installed, you might want to create a new account for the chat bot. Just go to this page to log out of your current account, then to this page to register a new one. chatbot-rb Second step is setting up chatbot-rb. If you don't know how to use Git, you can just use this link to download the chatbot-rb repository in a .zip file, and don't forget to extract that .zip file after you download it. If you do know how to use Git, git clone https://github.com/KockaAdmiralac/chatbot-rb.git Now, before you proceed you might want to enable viewing file extensions for known file types, if you're using Windows. To do that, you'd have to do something like this or this in your file explorer. If it doesn't appear for any reason, then go to Control Panel -> Appearance and Personalization -> File Explorer Options/Folder Options, select the "View" tab and in the Advanced settings find "Hide extensions for known file types" checkbox, uncheck it and save. After getting the code, you would need to modify the configuration to suit your needs. In the downloaded folder, you'll see main.sample.rb and config.sample.yml files. Rename them to main.rb and config.yml, respectively. Then open the config.yml file with a text editor (if there's no associated text editor with YML files on Windows, select Notepad). Replace "Username Here" with the username of your bot, "pa55w0rd h3r3" with the password of your bot and "communitytest (replace this with your wiki's URL, e.g. The My Little Pony wiki at https://mlp.wikia.com would have 'mlp' here)" with... well... exactly what is described. Don't forget to save the file. Then open your main.rb file and replace it with require_relative './client' # Configuration part 1 require_relative './plugins/admin' # End configuration part 1 $bot = Chatbot::Client.new $bot.register_plugins( # Configuration part 2 Chatbot::Admin # End configuration part 2 ) $bot.run! Don't forget to save the file. Testing Now you'd need to test if your installation is working. ; Windows : In the directory where config.yml and main.rb are, create a new text file and then rename it to start.bat. Then open it in Notepad, and insert @echo off ruby main.rb pause : in it. Then save that file and double-click on it to run it. ; Linux : In the directory where config.yml and main.rb are, create a new file and name it start.sh. Then open it, and insert ruby main.rb in it. Then save that file, run chmod +x start.sh to make it executable and then run it with ./start.sh ; Mac OS : No idea. If you see errors in the console window, or the bot isn't entering chat after running the file, check out the troubleshooting section. If you see bot entering the chat, enter !commands and it should list all available commands. Configuration Now, the bot has some commands, and that's nice, but you didn't run the bot just to have a few commands that aren't too useful in the long run, did you? You probably didn't, so you'd have to install plugins for chatbot-rb Installing plugins To install a plugin, you would have to modify your main.rb file. There are two configuration parts of it, first one is used for importing the plugins of the bot and the second one is used for registering them. Every plugin consists of their file name and class name. In the first configuration section, to import a plugin, add a line with require_relative './plugins/file_name' replacing file_name with the file name of the plugin. In the second configuration section, you can register imported plugins with adding their class names on a new line, but don't forget to separate them from earlier ones with a comma. For example: Chatbot::Admin, # You need a comma here because there's an element after it Chatbot::DiskLog # You don't need a comma here because it's the last element Available plugins Only plugins that may be of interest to a normal user are listed, there are additionally auto_tube, holo, notify_ban and sql_log plugins. ; admin : It's a plugin for general commands of the bot. It should be generally enabled. : Available commands: * !quit — Makes the bot quit the chat. Requires administrator permissions * !plugins — Lists all available plugins. Requires chat moderator permissions * !ignore user — Specified user will not be able to use bot commands in future. Requires chat moderator permissions * !unignore user — Reverts effects of !ignore. Requires chat moderator permissions * !commands — Lists all available commands * !source — Returns the link to the source code repository of chatbot-rb ; disk_log : This plugin makes the bot log chat into a file titled chat.log on the local disk. ; seen_tell : Provides a way of checking when was a user last online. : Also provides a way of delivering a message to a user that is offline. : Available commands: * !seen user — Checks when was a user last seen on chat * !tell user message — Tells the specified user a specified message. Note: Spaces in user parameter in !tell must be replaced with underscores, for example, Annabeth and Percy would become Annabeth_and_Percy * !untell user — Cancels the delivery of a message to the specified user * !told user — Checks if the message was delivered to the specified user * !tellon — Enables the !tell command. Requires chat moderator permissions * !telloff — Disables the !tell command. Requires chat moderator permissions * !seenon — Enables the !seen command. Requires chat moderator permissions * !seenoff — Disables the !seen command. Requires chat moderator permissions ; wiki_log : Makes the bot log the chat into wiki pages. : This plugin isn't guaranteed to work when the bot is hosted from a machine running Windows. : A on the bot would be advised if this plugin is enabled, so logging doesn't clog : Available commands: * !logs — Posts a link to Project:Chat/Logs page on the wiki. * !updated — Checks when were the logs last updated * !updatelogs — Updates chat logs manually. Requires chat moderator permissions : Upon installing the plugin the normal way, the following lines need to be inserted into config.yml: :wikilog: :log_interval: 3600 :title: Project:Chat/Logs/%d %B %Y :type: :daily :fifo_threshold: 5000 :category: Chat logs : To change the location of chat logs, change Project:Chat/Logs/%d %B %Y to something else. %d represents the date, %B month name and %Y year. : To change the category logs are categorized under, change Chat logs to something else. : To change how often are chat logs automatically updated, change 3600 to the number of seconds you want to update logs on. ; antispam : Automatic kicking/banning/warning of users upon matching certain rules. : See below for configuration. : Does not work on mods and the bot itself. Configuring antispam plugin In your config.yml file, add the following on the bottom: antispam: words: regex: warn: 1 kick: 2 ban: 3 time: 5 size: 10 length: 31536000000 reason: "Misbehaving in chat" warning: "%s: Please behave in chat" Adding these lines is the equivalent of not doing anything to configuration. However, now you can modify these options to your liking: ; words : This is the option for configuring the word filter. Every time somebody mentions a word from this list, they get an antispam point. : You can configure it as following: words: - word1 - word2 - word3 ; regex : If you want to use any regular expressions to detect bad words, you can put them here. : Format and behaviour is the same as for the words option. ; warn : After how many antispam points gained should the user be warned about their behavior. : Set to a very large number to (practically) disable. ; kick : After how many antispam points gained should the user be kicked from chat. : Set to a very large number to (practically) disable. ; ban : After how many antispam points gained should the user be banned from chat. : Set to a very large number to (practically) disable. ; warning : Message to be sent after the user reaches the warn limit. : If there's a %s in the message, it will be replaced with the user's username, only once. : For example, "%s, please be nice!" will show up as ", please be nice!" but "%s, %s, %s... you've deeply disappointed me." will throw an error and the warning won't be displayed. ; length : How many seconds will the ban last after the user reaches the ban limit. : By default set to 31536000000, which means infinite. ; reason : A reason for the ban after the user reaches the ban limit. : By default set to "Misbehaving in chat". ; size and time : These configuration options control after how many messages in which amount of time should the user gain an antispam point. : For example, if size is set to 10 and time is set to 5, like it is by default, a user will gain an antispam point if they write more than 10 messages in the span of 5 seconds. FAQ Also known as frequently asked questions. ; Can I run the bot from my account? : Only one instance of a user can be present in chat at once. That means if you're running the bot that logs into your account, once you enter the chat the bot would crash. So no, it's not advised to run the bot from your account. ; Can the bot kick and ban? : Yes, if it has chat moderator permissions and proper instructions on how to kick and ban. : If you need an automoderation plugin, I could write one for you if you ask to Kocka on his FANDOM Developers Wiki talkpage ; Do I need bot permissions on the bot account? : If the bot is supposed to log the chat onto the wiki, it would be advisable to to give bot permissions to the account, so it doesn't flood recent changes. : If it doesn't do any edits, no, it doesn't need bot rights. Troubleshooting If you encountered an error when starting the bot: # Check if your main.rb and config.yml files are set up properly # Ensure you didn't modify any other files # Make sure you installed Ruby and the dependencies. # Make sure username and password of the bot are correct If none of these worked, contact Kocka on His FANDOM Developers Wiki talkpage, paste your main.rb and config.yml files onto Pastebin and then link them to me as well, but do not forget to remove the password of the bot before pasting contents of config.yml. It would also be preferable if you copy or screenshot the error you're seeing in the console, if you're seeing one. Category:Handbooks